Games of Daze/Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso/x2ftp/msdos/libs/bcpp11/manual.txt

Text File | 1994-09-08 | 100.1 KB | 2,713 lines

==============================================================================

George Vanous                  THE BESTLibrary++

                                 documentation       last updated: Sep 8, 1994


NOTE  this library (and this documentation) is NOT complete!  I am still
      developing The BESTLibrary++, and am producing updates almost daily.

If this release is more than a week old, chances are I have made some
significant improvements -- just request the newest version and I will gladly
email it to you.

------------------------------------------------------------------------------

                               TABLE OF CONTENTS

PREFACE.................................introduction to The BESTLibrary++
BRIEF HISTORY...........................brief history of The BESTLibrary++
CODING STYLE............................Hungarian-Slovak coding convention
THE BESTLIBRARY++.......................documentation
 globals................................ global variables
 data types............................. data types (array, linked list, ...)
 graphics............................... graphics (bitmap, 2D/3D, primitives)
 keyboard............................... keyboard control
 string................................. string classes
 text mode.............................. text mode control/windowing
 timer.................................. timers and stopwatches
HOW TO CONTACT THE AUTHOR...............how to contact me
PROGRAMMING PITFALLS....................pitfalls I have experienced (USEFUL!)
PROGRAMMING TIPS........................tips I have found helpful   (USEFUL!)
PROGRAMMING IDEAS.......................ideas for programming projects
PROGRAMMING QUESTIONS...................some questions and answers
DOS DEBUG...............................DOS's DEBUG.COM commands
FREEWARE TITLES.........................quality freeware programs (incomplete)
DISCLAIMER..............................our legal system requires one of these

==============================================================================
----------------------------------  PREFACE  ---------------------------------

                   ----------------------------------------
                      GOALS OF WRITING THE BESTLIBRARY++
                   ----------------------------------------
There are several goals I am trying to meet with The BESTLibrary++:
1) provide a robust freeware C++ object library for all programmers
2) meet other programmers through email, telephone, or postal (snail) mail
3) create a base onto which other programmers can build on by offering
   their source code for inclusion in future releases of The BESTLibrary++

If we all help support freeware, we can ALL benefit.  See the end of this
documentation, under FREEWARE TITLES, for a catalog of known freeware.

                     ------------------------------------
                        IS THE BESTLIBRARY++ FREEWARE?
                     ------------------------------------
Of course.

I will release the library, documentation, and source to the demos as
freeware (as I did for The BESTLibrary v2.31, this library's predecessor).

AND I will also release the source code to The BESTLibrary++ to the public
domain.  With this gesture of good will (and 500++ hours of development time),
I hope you will take the time to leave some feedback to me, perhaps in the way
of suggestions on how to improve The BESTLibrary++, bug reports, or source
code contributions.

I want to hear from you!

                                --------------
                                   COMMENTS
                                --------------
If there is something you need that is not present in this library, please
contact me and I will probably input it.  If you find any mistakes or
inconsistencies in this documentation, do let me know.

This is no ordinary object library.  I have spent a great deal of time
designing an elegant class hierarchy (and think I have succeeded).  If you
have *any* recommendations or comments on my design, please let me know.  I
am always looking to improve this library.

You can contact me via email: [e-mail]
or call me at [phone] or write to me:  George Vanous
                                             8930 Watson Court
                                             Delta, BC
                                             V4C 4T6

Although I by no means require it, I do appreciate monetary donations.  I am
the typical university student who has to deal with expensive, rising tuition
fees, and pay for equally expensive course books.


                      -----------------------------------
                         WHAT THE BESTLIBRARY++ CAN DO
                      -----------------------------------
= data types
  - arrays, linked lists, queues, stacks
= graphics
  - SVGA upto 1280x1024x256 resolution (through SVGACC)
  - windows (primitive)
  - 2D primitives (line, rectangle, circle, etc.)
  - 2D vector movement, rotation, scaling
    - solid or wireframe display
    - multi-layer motion of solid 2D vector objects (can go "underneath")
  - 3D vector movement, rotation, scaling
    - solid surfaces with hidden surface removal or wireframe display
  - 55 screen clears and 4 screen fill patterns
= keyboard
  - keypress information
  - direct keyboard control to block out every key (CTRL-ALT-DEL, PAUSE, etc)
    - detect multiple keypresses (ie. holding down left and up arrow keys)
= text mode
  - cursor
  - windows (advanced)
    - multi-layer movement
    - resize, scroll
    - data entry
= timers
  - delays and stopwatches

                 --------------------------------------------
                    WHAT THE BESTLIBRARY++ CANNOT DO (YET)
                 --------------------------------------------
= graphics
  - 65000 and 16.7 million color modes
  - virtual reality world creation
  - 3D bitmap movement, rotation, scaling
  - 2D/3D texture mapping
  - 3D primitives (cube, sphere, etc.)
  - 2D bitmap multi-layer animation, rotation, scaling
  - .BMP/.GIF/.PCX/.ICO graphics manipulation
  - advanced graphics mode windowing
= text mode
  - region definitions inside windows
= string manipulation

         -----------------------------------------------------------
            PROGRAMS BEING WRITTEN FOR USE WITH THE BESTLIBRARY++
         -----------------------------------------------------------
= REALiTY EDITOR SuperVGA
  - can be used to draw:
    - 2D/3D vector graphics
    - bitmap icons for frame animation
    - texture surfaces for 2D/3D vector objects

                               ----------------
                                  THE FUTURE
                               ----------------
Peer into the crystal ball...

There are many projects I would like to see completed.  If you think you can
help out, please let me know:

1) hypertext word processor for creating documents with buttons, indexes,
   and more (maybe animation buttons, sound buttons, and picture buttons)

2) an entertainment pack that contains many small, but fun games; perhaps an
   arkanoid clone, towers of hanoi, pong, card games, trivia, and any other
   fun games

3) robust floppy/hard disk, tape drive, CD-ROM file cataloger, with
   descriptions, group categorization, searches, and quick index creation

4) multi-player civization game that does not stop at the space age!

5) superVGA 2D/3D graphics editor and animator for virtual reality creation

For more ideas, see PROGRAMMING IDEAS near the end of this documentation.

==============================================================================
-------------------------------  BRIEF HISTORY  ------------------------------

This library began as a collection of small .ASM functions written for
assembler programmers only.  It became The BESTLibrary 1.0, with 100+
functions for C programmers.  This eventually blossomed into the colossal 360
function library (v2.31).

I then discovered the benefits of object oriented programming using C++, and
began, in May, 1994, developing a true object library: The BESTLibrary++
(known in shorthand as BESTCPP).

==============================================================================
-------------------------------  CODING STYLE  -------------------------------

I have adopted the Hungarian-Slovak naming convention for naming variables.
After reading my reasons for using this convention, please leave me some
feedback on your opinions and preferences.

---

Hungarian Naming, or Hungarian for short, is named after the nationality of
the original developer, Charles Simonyi, who developed it as part of his
doctoral dissertation on programmer productivity.

It became widely used at Xerox PARC, where Simonyi was working when he
developed this practice.  It was adopted at Microsoft after Simonyi began
working there, and has since become a standard of sorts.

I have found that code written using Hungarian has become much easier to read
and understand.

---

In BASIC programs, variables tend to be as short as possible.
  20  LET B=10
  30  FOR A=1 TO 10
  40  LET B=B+A
  50  NEXT A

If short names are cryptic, perhaps longer names will be more useful?
  char  countOfCharacters;
  char *temporary_filename;
  int   number_of_files;
  word  windowhandle;
  long *pointerToArrayOfLongIntegers;

Hungarian is a compromise between these two extremes.
  char  ch;                            // 'ch' = character
  char  achFile[128];                  // 'a'  = array   'ch' = character
  char *pszName;                       // 'p'  = pointer 'sz' = string
  Window *pwMain;                      // 'p'  = pointer  'w' = window


HUNGARIAN VARIABLE NAMING

Apply short, lowercase prefixes onto each variable to denote its type:

  PREFIX   DATA TYPE
    a        array (compound type: ach aw)
    b        boolean
    ch       character
    d        double
    dw       unsigned long (double word)
    f        floating point
    gw       graphics window
    i        index (compound type: isz iach)
    l        long integer
    ll       linked list (compound type: llptw)
    p        pointer (compound type: pf, pu)
    n        integer
    sz       NULL-terminated string
    t        tri
    tw       text window
    u        function
    w        word
    y        byte

some not common prefixes

    bt       boot type
    chip     VGAChipset
    vm       video mode
    vmt      video mode type

Compound types can be strung together with other prefixes (ex. achFile[128])

For loop counters, use i, j, k, ...
  for (i = 0; i < wLength; i++) {
    for (j = 0; j < wHeight; j++) {
      ...
    }
  }

HUNGARIAN-SLOVAK VARIABLE NAMING

Hungarian-Slovak is a modified Hungarian naming convention created be me,
George Vanous (named after my nationality of birth -- however, I am now
Canadian).

Onto Hungarian, append suffixes that better describe the variable.
 void move(int nX_new, int nY_new);
 void move_rel(int nX_delta, int nY_delta);
 void copy_tmp() { nLength_tmp = nLength_new, nHeight_tmp = nHeight_new; }

  COMMON SUFFIXES   COMMON USES
       _avg           average value
       _cur           current value
       _def           definition
       _delta         a change in
       _dir           direction
       _init          initialization value
       _max           maximum value
       _min           minimum value
       _new           new value
       _old           old value
       _off           offset value
       _org           original value
       _tmp           temporary value


HUNGARIAN-SLOVAK FUNCTION NAMING

Eacho function contains a prefix that describes its purpose:
  bool is_cursor_on();
  void stretch_rel(int nX_delta, nY_delta);
  int  get_win_length();
  int  put_chr(int nX_new, int nY_new, char ch);
  void set_border_color(int nFgColor_new, int nBgColor_new);
Because they are always in lowercase, functions are easy to distinguish from
variables.

  COMMON PREFIXES   COMMON USES
       is_            functions that return bool
       get_           functions that return a value
       put_           functions that output something
       set_           functions that set something


HUNGARIAN-SLOVAK CLASS NAMING

Append the _def suffix for all inherited classes -- the useable class type
will never have a _def suffix:
  class _2d_location_def {
  protected:
    int nX, nY;
    ...
  };

  class _2d_pixel : public _2d_location_def {
    ...
  };

  .
  .
  .

  _2d_pixel mypixel;
This way, it is easy to distinguish classes that are designed to be inherited
from classes that are ready for use.

==============================================================================
-----------------------------  THE BESTLIBRARY++  ----------------------------

  --------------------------------------------------------------------------
-----------------------------------  NOTES  ----------------------------------

= angles are measured so that there are 256° in a full rotation (not 360°)
= all coordinates have a domain of -32767..32767
  - (0,0) is the center of the screen
  - x is positive right and negative left
  - y is positive down and negative up
  - z is positive towards and negative away
= some functions in BESTCPPx.HPP are not documented
  - this is not an error; these functions represent undocumented features

  --------------------------------------------------------------------------
--------------------------------  DATA TYPES  --------------------------------

array...................arrays for random access
list, linked, double....doubly linked list for faster searches
list, linked, single....singly linked list for less memory consumption
list, lisp..............Lisp-like lists
queue...................queues for FIFO access
stack...................stacks for LIFO access

  --------------------------------------------------------------------------
---------------------------------  GRAPHICS  ---------------------------------

2D bitmap objects.......movement, rotation, scaling of 2D bitmap objects
2D vector objects.......movement, rotation, scaling of 2D vector objects
3D bitmap objects.......movement, rotation, scaling of 3D bitmap objects
3D vector objects.......movement, rotation, scaling of 3D vector objects
primitives..............pixels, lines, squares/rectangle, circles/ellipses
screen fills............various background patterns and screen clears
windowing...............simple window definitions and scrolling

  --------------------------------------------------------------------------
---------------------------------  KEYBOARD  ---------------------------------

keyboard................keypress information, direct control, multi-key press

  --------------------------------------------------------------------------
---------------------------------  TEXT MODE  --------------------------------

cursor..................text cursor control
special effects.........special text mode effects
windowing...............multi-layer windowing: moving, resizing, data entry

  --------------------------------------------------------------------------
-----------------------------------  TIMER  ----------------------------------

timer...................delays and stopwatches

  --------------------------------------------------------------------------
----------------------------------  STRING  ----------------------------------

string..................string functions

==============================================================================


==============================================================================
----------------------------------  GLOBALS  ---------------------------------

GLOBAL TYPES
------------
pFunc                                  // function pointer
ptw                                    // text window pointer
byte                                   // (0-255) type as in Pascal
shortint                               // (-128 to +127) type as in Pascal
word                                   // (0-65535) type as in Pascal
dword                                  // (0-4,294,967,295)

bool   { false, true }
tri    { no, yes, sortof }
action { nothing, all, morphing, moving, rotating, scaling, stretching, wireframe_toggle }
colors { black, blue, green, cyan, red, magenta, brown, lightgray, darkgray,
         lightblue, lightgreen, lightcyan, lightred, lightmagenta, yellow,
         white }
boot_type  { cold, warm }
alignment  { none, horizontal, vertical, center, right_justify }
direction  { stop, up, left, down, right, up_left, down_left, down_right,
             up_right }
video_mode { _80x25, _80x50, _640x480x16, _320x200x256, _640x400x256,
             _640x480x256, _800x600x256, _1024x768x256, _1280x1024x256 }
video_mode_type { _text, _mono, _graphics }
cpu_type { _8086, _8088, _80186, _80286, _80386, _80486, _80586 }

days   { Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday }
days3  { Mon, Tue, Wed, Thu, Fri, Sat, Sun }
months { January, February, March, April, May, June, July, August, September,
         October, November, December }

cards       { two, three, four, five, six, seven, eight, nine, jack, queen,
              king, ace }
card_suites { clubs, spades, hearts, diamonds }

continents { Africa, Antarctica, Arctic, Asia, Europe, NorthAmerica,
             SouthAmerica }
provinces  { BritishColumbia, Albert, Saskatchewan, Manitoba, Ontario, Quebec,
             NovaScotia, NewBrunswick, PrinceEdwardIsland, PEI, Yukon,
             NorthwestTerritories }

GLOBAL VARIABLES
----------------
const int viewx1, viewy1,              // provided by SVGACC
          viewx2, viewy2;              // current viewport dimensions
int viewz1, viewz2;                    // provided by The BESTLibrary++
bool abKeys[256];                      // keys currently depressed
byte ayKeypadKeys[],                   // keypad movement keys
     ayOKSPKeys[],                     // OK;. movement keys
     ayTFHBKeys[],                     // TFHB movement keys
     ayWADXKeys[],                     // WADX movement keys
     ayWindowSingle[],                 // single border all around
     ayWindowDouble[],                 // double border all around
     ayWindowSolid[],                  // solid border all around
     ayWindowSingleTop[],              // single top/bottom, double sides
     ayWindowDoubleTop[],              // double top/bottom, single sides
     ayWindowSingleTopOnly[],          // single top/bottom, no sides
     ayWindowDoubleTopOnly[],          // double top/bottom, no sides
     ayWindowSolidTopOnly[];           // solid top/bottom, no sides
char **pachVGACards,                   // description of every supported card
     **pachVGAFonts;                   // available font filenames
int nX_max, nY_max,                    // maximum (x,y) set by BESTCPP
   *pnLookupAtan,                      // integer arctan lookup table
   *pnLookupSin,                       // integer sine lookup table
   *pnLookupCos;                       // integer cosine lookup table
long *plLookupSin,                     // long sine lookup table
     *plLookupCos,                     // long cosine lookup table
     *plLookupSlopeX,                  // long slope run lookup table
     *plLookupSlopeY;                  // long slope rise lookup table
float *pfLookupSin,                    // float sine lookup table
      *pfLookupCos;                    // float cosine lookup table
keyboard_def   key;                    // handle keypresses
mouse_def      mouse;                  // handle mouse
txt_screen_def txt;                    // text screen
video_def      video;                  // video mode information
MouseCursor
  msArrowBig,                          // arrow directions
  msArrowDiag1, msArrowDiag2,
  msArrowHand1, msArrowHand2, msArrowHand3, msArrowHand4, msArrowHand5, msArrowHand6,
  msArrowHorz,
  msArrowInput,
  msArrowNorm,
  msArrowVert1, msArrowVert2,
  msClock,                             // shapes
  msPickbox1, msPickbox2, msPickbox3, msPickbox4, msPickbox5, msPickbox6, msPickbox7, msPickbox8,
  msPixel,
  msSquare,
  msXHairs;

==============================================================================
--------------------------------  DATA TYPES  --------------------------------

------------------------------------------------------------------------------
Array
-----
NOTES:
> The bottom of the array is the item that was first "add"ed.  The top is the
  most recently "add"ed item.
> Because it takes some time for the array to resize itself when it gets full,
  take care to use an initial number of slots so as to minimize resizing.

constructor: array_def(word wCount_init = 5);
> "count_init" is the initial number of indexes (this is not a maximum -- the
  number of indexes will grow automatically when there are no more free ones,
  by increments of "count_init")

void add(T item);
> add "item" onto the top of the array

void apply(void (*func)(T& item));
> call "func" for each element in the array, passing in each "item"

bool find(T item, word& wIndex);
> search for "item" in the array
> RETURNS  true  - successful ("wIndex" is index to item)
           false - "item" was not found in array

T get_bottom();
> RETURNS  item at bottom of array (first item "add"ed)

T get_current();
> RETURNS  item at current index

T get_index(word wIndex);
> RETURNS  item at "wIndex"
           0 - "wIndex" is not a valid index (if it exceeds array)

T get_next(word wOffset = 1);
> RETURNS  item at "wOffset" slots above current index
           0 - "wOffset" slots above current index exceeds array

T get_prev(word wOffset = 1);
> RETURNS  item at "wOffset" slots under current index
           0 - "wOffset" slots under current index exceeds array

T get_top();
> RETURNS  item at top of array (most recently "add"ed item)

bool goto_bottom();
> set the current index to the bottom of the array
> RETURNS  true  - successful
           false - array is empty

bool goto_index(word wIndex);
> set the current index to "wIndex"
> RETURNS  true  - successful
           false - there is no such index (it exceeds array)

bool goto_next(word wOffset = 1);
> go forward "wOffset" slots from the current index
> RETURNS  true  - successful
           false - there is no such index (array is empty or at top)

bool goto_prev(word wOffset = 1);
> go backward "wOffset" slots from the current index
> RETURNS  true  - successful
           false - there is no such index (array is empty or at bottom)

bool goto_top();
> set the current index to the top of the array
> RETURNS  true  - successful
           false - array is empty

bool insert(T item, word wIndex);
> insert "item" into the array at "wIndex"
> RETURNS  true  - successful
           false - "wIndex" exceeds array by more than 1

bool insert_to_bottom(T item);
> insert "item" into the bottom of the array
> RETURNS  true  - successful
           false - array is empty

bool is_empty();
> RETURNS  true  - array is empty
           false - array is not empty

bool is_in(T item);
> RETURNS  true  - "item" is in array
           false - "item" is not in array

bool move(T item, word wIndex);
> move "item" from its current position in the array to "wIndex"
> RETURNS  true  - successful
           false - "item" was not found in array or "wIndex" exceeds array

bool move_to_bottom(T item);
> move "item" to the bottom of the array
> RETURNS  true  - successful
           false - "item" was not found in array

bool move_to_top(T item);
> move "item" to the top of the array
> RETURNS  true  - successful
           false - "item" was not found in array

bool remove(T item);
> remove "item"
> RETURNS  true  - successful
           false - "item" was not found in array

bool remove_bottom();
> remove the bottom item from the array
> RETURNS  true  - successful
           false - array is empty

bool remove_current();
> remove the item at the current index
> RETURNS  true  - successful
           false - array is empty

bool remove_index(word wIndex);
> remove the item at "wIndex"
> RETURNS  true  - successful
           false - there is no such index (it exceeds array)

bool remove_next(word wOffset = 1);
> remove the item that is "wOffset" slots above the current index
> RETURNS  true  - successful
           false - there is no such index (array is empty or exceeds array)

bool remove_prev(word wOffset = 1);
> remove the item that is "wOffset" slots below the current index
> RETURNS  true  - successful
           false - there is no such index (array is empty or exceeds array)

bool remove_top();
> remove the top item from the array
> RETURNS  true  - successful
           false - array is empty

void shuffle();
> randomizes the order of items in the array

void sort(int (*fcmp)(const void *, const void *));
= "fcmp" is a user-defined comparison routine that compares two items
  and returns a value based on the comparison:

    int fcmp(const void *a, const void *b);
    returns <  0  if a <  b
            == 0  if a == b
            >  0  if a >  b

    int sort_function(const void *pA, const void *pB);

    void main()
    {
      array_def<int> myarray(4);
      myarray.add(5); myarray.add(3); myarray.add(12); myarray.add(7);
      myarray.sort(sort_function);
    }

    /* to illustrate the long way... */
    int sort_function(const void *pA, const void *pB)
    {
      if (*(int *)pA  < *(int *)pB) return -1;
      if (*(int *)pA == *(int *)pB) return  0;
      if (*(int *)pA  > *(int *)pB) return  1;
    }
    /* the faster, better way is illustrated in the example program */

EXAMPLE PROGRAM:

#include "bestcpp.hpp"

void add_one(int& iTo);
int sort_function(const void *pA, const void *pB);

void main()
{
  #define SHOW_ARRAY \
  cout << "bottom = "       << myarray.get_bottom()  <<      \
          ", top = "        << myarray.get_top()     <<      \
          ", next = "       << myarray.get_next()    <<      \
          ", current = "    << myarray.get_current() <<      \
          ", previous = "   << myarray.get_prev()    <<      \
          ", at index 2 = " << myarray.get_index(2)  << endl;

  word wIndex;
  array_def<int> myarray(3);           // array of integers (3 slots)

  myarray.add(3);                      // add 3 onto array
  myarray.add(5);                      // add 5 onto array
  myarray.add(6);                      // add 6 onto array
  myarray.add(7);                      // add 7 onto array
  myarray.add(8);                      // add 8 onto array
  myarray.add(9);                      // add 9 onto array
  myarray.add(10);                     // add 10 onto array
  myarray.insert_to_bottom(2);         // add 2 onto the bottom of the array

  myarray.move_to_top(3);              // move 3 to the top of array
  myarray.move_to_bottom(6);           // move 6 to the bottom of array
  myarray.move(5, 1);                  // move 5 to index 1
  myarray.move(5, 3);                  // move 5 to index 3
  myarray.find(5, wIndex);             // get the index of 5
  myarray.insert(4, wIndex);           // insert 4 just before 5
  myarray.goto_bottom();               // go to beginning of array
  myarray.goto_next(2);                // jump 2 items in array
  myarray.remove_current();            // remove currently indexed item
  SHOW_ARRAY;                          // display current array contents

  myarray.shuffle();
  SHOW_ARRAY;                          // display current array contents
  myarray.sort(sort_function);
  myarray.apply(add_one);              // add one to each number in array

  myarray.remove_index(1);             // remove item at index 1 from array
  myarray.goto_index(2);
  myarray.remove(4);                   // remove 4 from array

  if (!myarray.is_in(4))
    cout << "4 is not in the array" << endl;
  if (!myarray.is_empty())
    cout << "array is not empty" << endl;
}

void add_one(int& iTo)
{
  iTo++;
}

int sort_function(const void *pA, const void *pB)
{
  return *(int *)pA - *(int *)pB;
}

------------------------------------------------------------------------------
List, Linked, Double
--------------------
NOTES:
> All functions are identical to "List, Linked, Single", with all references
  to "single" changed to "double":
  - "list_single" becomes "list_double"
  - "node_s" becomes "node_d"
> Two differences arise from the addition of a "previous" pointer in the
  doubly-linked list class
  1) Going to the previous node is faster (the singly linked list class has
     only a "next" pointer, so it has to search from the head of the linked
     list to find the previous node).
  2) Unlinking a node is faster simply because finding the previous node is
     faster.

EXAMPLE PROGRAM:

#include "bestcpp.hpp"

void add_one(int *piTo);

void main()
{
  list_double<int> mylist;             // linked list of integers
  int *piX = new int(5),               // pointer to integer = 5
      *piY = new int(10);              // pointer to integer = 10

  mylist.link(piX);                    // link in "piX"
  mylist.link(piY);                    // link in "piY"

  mylist.apply(add_one);               // add one to each number in list

  mylist.unlink(piX);                  // unlink "piX"
  bool bFlag = mylist.unlink(piX);     // won't unlink again: returns false
  cout << "flag = " << bFlag << endl;

  node_d<int> *pNode = mylist.find(piY); // get the node containing "piY"
  mylist.unlink(pNode);                // unlink it

  if (mylist.is_empty())               // if linked list is empty
    cout << "doubly linked list is empty" << endl;
}

void add_one(int *piTo)
{
  (*piTo)++;
}

------------------------------------------------------------------------------
List, Linked, Single
--------------------
NOTES:
> Never link the same pointer into more than one linked list
> After an unlink, you are responsible for deallocating the pointer
> Every item pushed must have been dynamically allocated with "new" (not
  new[]).  This is so the class destructor can delete every item.

constructor: list_single();

void apply(void (*func)(T *pItem));
> call "func" for each node in the linked list, passing in each node's "pItem"

node_s<T> *find(T *pItemToFind);
> search for "pItemToFind" in linked list
> RETURNS  node containing "pItemToFind"
           0 - "pItemToFind" is not contained in linked list

bool is_empty();
> RETURNS  true  - linked list is empty
           false - linked list is not empty

T *get_current();
> RETURNS  item at current node

void goto_head();
> set the current node to the head of the list

bool goto_next();
> go to the next node (from the current node)
> RETURNS  true  - successful
           false - there is no next node (list is empty or at end of list)

bool goto_prev();
> go to the previous node (from the current node)
> RETURNS  true  - successful
           false - there is no previous node (list is empty or at head of list)

void link(T *pItem_new);
> insert "pItem_new" into linked list

bool unlink(T *pItemToDelete);
> unlink "item" from linked list and delete it
> RETURNS  true  - successful
           false - "item" is not contained in linked list

bool unlink(node_s<T> *pNodeToDelete);
> unlink "node" from linked list and delete it
> RETURNS  true  - successful
           false - "node" = 0 or linked list is empty

EXAMPLE PROGRAM:

#include "bestcpp.hpp"

void add_one(int *piTo);

void main()
{
  list_single<int> mylist;             // linked list of integers
  int *piX = new int(5),               // pointer to integer = 5
      *piY = new int(10);              // pointer to integer = 10

  mylist.link(piX);                    // link in "piX"
  mylist.link(piY);                    // link in "piY"

  mylist.apply(add_one);               // add one to each number in list

  mylist.unlink(piX);                  // unlink "piX"
  bool bFlag = mylist.unlink(piX);     // won't unlink again: returns false
  cout << "flag = " << bFlag << endl;

  node_s<int> *pNode = mylist.find(piY); // get the node containing "piY"
  mylist.unlink(pNode);                // unlink it

  if (mylist.is_empty())               // if linked list is empty
    cout << "singly linked list is empty" << endl;
}

void add_one(int *piTo)
{
  (*piTo)++;
}

------------------------------------------------------------------------------
List, Lisp
----------

Not written yet :(

------------------------------------------------------------------------------
Queue
-----
NOTES:
> Never enqueue the same pointer into more than one queue
> After a dequeue, you are responsible for deallocating the pointer
> Every item enqueued must have been dynamically allocated with "new" (not
  new[]).  This is so because the class destructor can delete every item.

constructor: queue_def(word wInitialSize_init = 5);
> the size of the queue will be set to "wInitialSize_init" elements -- the
  size will increase in increments of "wInitialSize_init" when the queue gets
  full

void apply(void (*func)(T *pItem));
> call "func" for each element in the queue, passing in each element's "pItem"

T *dequeue();
> RETURNS  item first enqueued
           0 - no more items in queue

void enqueue(T *pItem_new);
> enqueue "pItem_new" into queue

bool is_empty();
> RETURNS  true  - queue is empty
           false - queue is not empty

EXAMPLE PROGRAM:

#include "bestcpp.hpp"

void add_one(int *piTo);

void main()
{
  queue_def<int> myqueue;              // queue for 5 (initially) integers
  int *piX = new int(5),               // pointer to integer = 5
      *piY,
      *piZ = new int(10);              // pointer to integer = 10

  myqueue.enqueue(piX);                // add in "piX" (pointer to 5)
  myqueue.enqueue(piZ);                // add in "piZ" (pointer to 10)

  myqueue.apply(add_one);              // add one to each number in list

  piY = myqueue.dequeue();             // get first value added
  cout << "Y = " << *piY << endl;
  delete piY;                          // deallocate

  piY = myqueue.dequeue();             // try on empty queue: returns 0
  cout << "Y = " << *piY << endl;
  delete piY;                          // deallocate

  if (myqueue.is_empty())              // if queue is empty
    cout << "queue is empty" << endl;
}

void add_one(int *piTo)
{
  (*piTo)++;
}

------------------------------------------------------------------------------
Stack
-----
NOTES:
> Never push the same pointer onto more than one stack
> After a pop, you are responsible for deallocating the pointer
> Any items not popped are deallocated by the class destructor

constructor: stack_def();

void apply(void (*func)(T *pItem));
> call "func" for each node in the stack, passing in each node's "pItem"

bool is_empty();
> RETURNS  true  - stack is empty
           false - stack is not empty

T *pop();
> RETURNS  item last pushed
           0 - no more items on stack

bool push(T *pItem_new);
> push "pItem_new" onto stack
> RETURNS  true  - successful
           false - "pItem_new" = 0

EXAMPLE PROGRAM:

#include "bestcpp.hpp"

void add_one(int *piTo);

void main()
{
  stack_def<int> mystack;              // stack of integers
  int *piX = new int(5);               // pointer to integer = 5
  int *piY,
      *piZ = new int(10);              // pointer to integer = 10

  mystack.push(piX);                   // push "piX" on stack
  mystack.push(piZ);                   // push "piZ" on stack

  mystack.apply(add_one);              // add one to each number in list

  piY = mystack.pop();                 // pop off last value pushed on
  cout << "Y = " << *piY << endl;
  delete piY;                          // deallocate

  piY = mystack.pop();                 // try on empty stack: returns 0
  cout << "Y = " << *piY << endl;
  delete piY;                          // deallocate

  if (mystack.is_empty())              // if stack is empty
    cout << "stack is empty" << endl;
}

void add_one(int *piTo)
{
  (*piTo)++;
}

==============================================================================


==============================================================================
---------------------------------  GRAPHICS  ---------------------------------

NOTES:
> Graphics will only show themselves on one page at a time.
> "show()" and "hide()" will display only if object is "set_visible(true)"
> For flicker-free animation, make sure "video.page_swap()" is called before
  any animation begins.
> When all objects have been "show()"n, call "video.done()", then "done()"
  for all the objects.
    _2d_line myline(50, 100, 50, 30, yellow);
    _2d_circle mycircle(10, 10, 50, lightgreen, true);
    video.page_swap();                 // need to do this before animation

    while (true) {                     // endless loop
      myline.move(-10, -5);            // move the line
      mycircle.move(10, 5);            // move the circle

      myline.show();                   // done manipulating -- show it now
      mycircle.show();                 // done manipulating -- show it now

      video.done();                    // needed after everything is "show()"n

      myline.done();                   // tell all objects they are "done()"
      mycircle.done();                 // tell all objects they are "done()"
    }

COMMON TO ALL GRAPHIC OBJECTS
-----------------------------
DEFAULT VALUES:
> movement keys       = ayKeypadKeys
> movement steps      = 5
> movement directions = 1
> movement increments = 1
> set_move_mode(1)
> stop_moving()         "set_move_mode(1)" calls "start_moving()"

void done();
> perform cleanup work after a "show()" and "video.done()"

int get_x();
> RETURNS  x-coordinate of object

int get_y();
> RETURNS  y-coordinate of object

byte get_move_mode();
> RETURNS  mode of movement

byte get_rebound_mode();
> RETURNS  method of dealing with border collisions

void hide();
> hide the object from the current active page

void interact(void (*puBg)(bool bShow) = 0);
> give the user control over the graphic object
> calls function "puBg(true)"  during interaction (to show all graphics)
> calls function "puBg(false)" during interaction (to hide all graphics)
> RETURNS  when user presses ENTER or ESC

void interact_move();
> if a movement key was pressed, the object is moved accordingly
> if the object is in motion, the object is moved accordingly

bool is_onscreen(int nX_new, int nY_new);
> RETURNS  true  - object is onscreen at "nX_new","nY_new"
           false - object is not onscreen at "nX_new","nY_new"

bool is_onscreen_rel(int nX_delta, int nY_delta);
> RETURNS  true  - object is onscreen "nX_delta","nY_delta" from its current
                   position
           false - object is not onscreen "nX_delta","nY_delta" from its
                   current position

bool is_visible();
> RETURNS  true  - object is visible
           false - object is hidden

bool is_wireframe();
> RETURNS  true  - the object is in wireframe mode
           false - the object has its hidden surfaces removed

void rebound();
> rebound the object (called after "is_onscreen()" returns false)
> if this is the fourth time calling rebound with similar coordinates, the
  object is placed into the center of the screen

void set_keys_move(byte *ayKeysMove_new);
> "ayKeysMove_new" become the movement keys

void set_move_mode(byte yMoveMode_new, bool bSetup);
> set the mode of movement
> "bsetup" is true  - defaults are set
              false - defaults are not set
> "yMoveMode_new" is
   0 - thrust and brake only;  moves to match the currently facing direction
       since only a movement step along the y-axis is required, the movement
         step along the x-axis is set to 0
       defaults: set_rebound(2);
                 start_moving();
   1 - motion in 8 directions; rotates to match the currently facing direction
       defaults: set_rebound(1);
                 start_moving();
   2 - motion in 8 directions; rotates in multiples of 45° only
       defaults: set_rebound(3);
                 start_moving();

void set_rebound(byte yReboundMode_new);
> set the method of dealing with border collisions
  "yReboundMode_new" is
   0 - no checking for borders and no rebounding
   1 - if border is hit, rebound occurs
   2 - if border is hit, object appear on opposite side of screen
   3 - if border is hit, object stops moving in that direction

void set_visible(bool bVisible_new = true);
> "bVisible_new" is true  - object is visible
                    false - object is hidden

void set_wireframe(bool bWireframe_new = true);
> "bWireframe_new" is true  - the object is wireframe
                      false - the object is solid

void show();
> show the object on the current display page

void start_moving();
> start moving the object according to its direction and step rates

void stop_moving();
> stop moving the object

--------
MOVEMENT
--------
int get_move_x_dir();
> RETURNS  direction of movement along x-axis (-1 = left, +1 = right)

int get_move_y_dir();
> RETURNS  direction of movement along y-axis (-1 = up, +1 = down)

int get_move_x_inc();
> RETURNS  movement increment along x-axis

int get_move_y_inc();
> RETURNS  movement increment along y-axis

int get_move_x_step();
> RETURNS  movement rate along x-axis

int get_move_y_step();
> RETURNS  movement rate along y-axis

bool is_moving()
> RETURNS  true  - object is moving according to its direction and step rates
           false - object is not moving

bool is_moving_somewhere()
> RETURNS  true  - object is in motion (nonzero direction and step rates)
           false - object is not in motion (zero direction and step rates)

void move();
> move the object by its movement increments

void move(int nX_new, int nY_new);
> move the object to coordinates "nX_new","nY_new"

void move_rel(int nX_delta, int nY_delta);
> move the object "nX_delta","nY_delta" from its current position

void set_move_dir(int nMoveDir_new);
> set the movement directions along the x-axis and y-axis to "nMoveDir_new"
> typical values are -1 (left), +1 (right)
> this is multiplied with the step when moving (ex. 2 would double the speed)

void set_move_inc(int nMoveInc_new);
> set the movement increments along the x-axis and y-axis to "nMoveXInc_new"

void set_move_inc_rel(int nMoveInc_delta);
> set the movement increments along the x-axis and y-axis "nMoveXInc_delta"
  from their current values

void set_move_step(int nMove_new);
> set the movement step along the x-axis and y-axis to "nMove_new"

void set_move_step_rel(int nMove_delta);
> set the movement step along the x-axis and y-axis "nMove_delta" from its
  current value

void set_move_x_dir(int nMoveXDir_new);
> set the movement direction along the x-axis to "nMoveXDir_new"
> typical values are -1 (left), 0 (stop), +1 (right)
> this is multiplied with the step when moving (ex. 2 would double the speed)

void set_move_y_dir(int nMoveYDir_new);
> set the movement direction along the y-axis to "nMoveYDir_new"
> typical values are -1 (left), 0 (stop), +1 (right)
> this is multiplied with the step when moving (ex. 2 would double the speed)

void set_move_x_inc(int nMoveXInc_new);
> set the movement increments along the x-axis to "nMoveXInc_new"

void set_move_y_inc(int nMoveYInc_new);
> set the movement increments along the y-axis to "nMoveYInc_new"

void set_move_x_inc_rel(int nMoveXInc_delta);
> set the movement increments along the x-axis "nMoveXInc_delta" from its
  current value

void set_move_y_inc_rel(int nMoveYInc_delta);
> set the movement increments along the y-axis "nMoveYInc_delta" from its
  current value

void set_move_x_step(int nMoveX_new);
> set the movement step along the x-axis to "nMoveX_new"

void set_move_y_step(int nMoveY_new);
> set the movement step along the y-axis to "nMoveY_new"

void set_move_x_step_rel(int nMoveX_delta);
> set the movement step along the x-axis "nMoveX_delta" from its current
  value

void set_move_y_step_rel(int nMoveY_delta);
> set the movement step along the y-axis "nMoveY_delta" from its current
  value

COMMON TO ALL GRAPHIC OBJECTS THAT CAN STRETCH THEMSELVES
--------------------------------------------------------
void interact_stretch();
> if a stretch key was pressed, the object is stretched accordingly
> if the object is in a continuous stretch, the object is stretched
  accordingly

COMMON TO ALL GRAPHIC OBJECTS THAT CAN ROTATE THEMSELVES
--------------------------------------------------------
int  get_x_axis()                                      { return nXAxis; }
int  get_y_axis()                                      { return nYAxis; }
int  get_angle()                                       { return nAngle; }
void interact_spin();
void rotate(int nAngle_new)                            { rotscale(nAngle_new, nScale); }
void rotate_rel(int nAngle_delta)                      { rotate(nAngle+nAngle_delta); }
void rotscale_rel(int nAngle_delta, int nScale_delta)  { rotscale(nAngle+nAngle_delta, nScale+nScale_delta); }
void scale(int nScale_new)                             { rotscale(nAngle, nScale_new); }
void scale_rel(int nScale_delta)                       { scale(nScale+nScale_delta); }
void set_axes(int nX_new, int nY_new);
void set_axes_rel(int nX_delta, int nY_delta)          { set_axes(nXAxis+nX_delta, nYAxis+nY_delta); }
void set_x_axis(int nX_new)                            { set_axes(nX_new, nYAxis); }
void set_x_axis_rel(int nX_delta)                      { set_x_axis(nXAxis+nX_delta); }
void set_y_axis(int nY_new)                            { set_axes(nXAxis, nY_new); }
void set_y_axis_rel(int nY_delta)                      { set_y_axis(nYAxis+nY_delta); }
virtual void reset() = 0;                                // pure virtual
virtual void rotscale(int nAngle_new, int nScale_new) = 0; // pure virtual

void interact_rotate();
> if a rotation key was pressed, the object is rotated accordingly
> if the object is in rotation, the object is rotated accordingly

void interact_scale();
> if a scale key was pressed, the object is scale accordingly
> if the object is in a continuous scale, the object is scaled accordingly

void set_keys_orbit(byte *ayKeysOrbit_new);
> "ayKeysOrbit_new" become the orbit keys

void set_keys_rotate(byte *ayKeysRotate_new);
> "ayKeysRotate_new" become the rotate keys

void set_keys_scale(byte *ayKeysScale_new);
> "ayKeysScale_new" become the scale keys

void set_move_mode(byte yMoveMode_new);
> set the mode of movement (each mode is simply a macro)
  "yMoveMode_new" is
   0 - thrust and brake only; motion determined by rotation
       set_rebound(2);
       ayRotateKeys = ayMoveKeys;
   1 - motion in 8 directions; rotation determined by direction
       set_rebound(1);
   2 - motion in 8 directions; rotation determined by player
       set_rebound(3);

==============================================================================
2D vector objects
=================
constructor: _2d_object_vector(int nX_init, int nY_init,
                               int *object_init, int *object_data_init,
                               byte movement_mode = 0,
                               byte *keys_move_init = keypad_keys,
                               byte *keys_rotate_init = wadx_keys,
                               int x_axis_init = 0, int y_axis_init = 0,
                               bool visible_init = true);
> "nX_init","nY_init" are the object's coordinates
> "movement_mode" is the mode of movement [see "set_movement" for the modes]
> "object_init" is the array of vector coordinates
> "object_data_init" is the array of commands to draw the object
> "x_axis_init","y_axis_init" are the axes
> "visible_init" is true  - object is visible
                    false - object is hidden

void reset();
> reset the object to its initial state

----
AXES
----
int get_x_axis();
> RETURNS  x-axis position of object

int get_y_axis();
> RETURNS  y-axis position of object

int get_angle();
> RETURNS  angle of rotation of object

void set_axes(int nX_new, int nY_new);
> set the x-axis and y-axis to "nX_new","nY_new"

void set_axes_rel(int nX_delta, int nY_delta);
> set the x-axis and y-axis "nX_delta","nY_delta" from their current positions

void set_x_axis(int nX_new);
> set the x-axis to "nX_new"

void set_x_axis_rel(int nX_delta);
> set the x-axis "nX_delta" from its current position

void set_y_axis(int nY_new);
> set the y-axis to "nY_new"

void set_y_axis_rel(int nY_delta);
> set the y-axis "nY_delta" from its current position

--------
MOVEMENT
--------
int get_rate_move();
> RETURNS  movement rate factor

int get_rate_rot();
> RETURNS  rotation rate factor

void set_move_rate(int rate_move_new);
> set the movement rate factor to "rate_move_new"

void set_move_rate_rel(int rate_move_delta);
> set the movement rate factor "rate_move_delta" from its current movement
  rate

void set_rotation_rate(int rate_rot_new);
> set the rotation rate factor to "rate_rot_new"

void set_rotation_rate_rel(int rate_rot_delta);
> set the rotation rate factor "rate_rot_delta" from its current rotation rate

----------------
ROTATION/SCALING
----------------
void rotate(int angle_to);
> rotate the object to "angle_to" degrees

void rotate_rel(int angle_delta);
> rotate the object "angle_to" degrees from its current rotation angle

void scale(int scale_to);
> scale the object to "scale_to" (128 means original size)

void scale_rel(int scale_delta);
> scale the object "scale_to" from its current scale factor

void rotscale(int angle_to, int scale_to);
> rotate the object to "angle_to" degrees
> scale the object to "scale_to" (128 means original size)

void rotscale_rel(int angle_delta, int scale_delta);
> rotate the object "angle_to" degrees from its current rotation
> scale the object "scale_to" from its current scale factor

EXAMPLE PROGRAM:

#include "bestcpp.hpp"

/* vertex coordinates */
// x,y,z of every vertex
// 32767  end of object
int pic_box[] = {
   -40,   40,  // box body                            //   0  left  down
   -40,  -40,                                         //   2  left  up
    40,  -40,                                         //   4  right up
    40,   40,                                         //   6  right down

    32767
};

/* data describing each vector */
// -2  new polygon (enclosed), number of vertexes, vertex offset
// -1  new polygon (not enclosed), number of vertexes, vertex offset
//  32767  end of object
int pic_box_data[] = {
    -2,   4,   0, lightgreen,   // box body
               2, lightgreen,
               4, lightgreen,
               6, lightgreen,
    32767
};

void main()
{
  video.set(_640x480x256);             // set video mode to 640x480 256 colors

  _2d_object_vector box(nX_max/2, nY_max/2, pic_box, pic_box_data);
  box.move_rel(10, -10);               // move box
  box.rotate_rel(10, 10);              // rotate box
  box.scale_rel(108, 142);             // scale box

  key.clear();                         // clear any keypress information
  do {
    key.get_ch_ready();                // get a key if one is pressed

    box.automatic();                   // automatically do movement/rotation

    msec(15);                          // wait 15 milliseconds
  } while (key.get_scan() != SCAN_ESC);
}

==============================================================================
3D vector objects
=================
constructor: _3d_object_vector(int nX_init, int nY_init, int z_init,
                               int *object_init, int *object_data_init,
                               int x_axis_init = 0, int y_axis_init = 0,
                               int z_axis_init = 0,
                               bool wireframe_init = false,
                               bool visible_init = true);
> "nX_init","nY_init","z_init" are the 3D object's coordinates
> "object_init" is the array of vector coordinates
> "object_data_init" is the array of commands to draw the object
> "x_axis_init","y_axis_init","z_axis_init" are the axes
> "wireframe_init" is true  - object is in wireframe
                      false - object has its hidden surfaces removed
> "visible_init" is true  - object is visible
                    false - object is hidden

void reset();
> reset the object to its initial state

----
AXES
----
int get_x();
> RETURNS  the x-coordinate of the object

int get_x_axis();
> RETURNS  the x-axis position of the object

int get_y();
> RETURNS  the y-coordinate of the object

int get_y_axis();
> RETURNS  the y-axis position of the object

int get_z();
> RETURNS  the z-coordinate of the object

int get_z_axis();
> RETURNS  the z-axis position of the object

void set_axes(int nX_new, int nY_new, int nZ_new);
> set the x,y,z-axes to "nX_new","nY_new","nZ_new"

void set_axes_rel(int nX_delta, int nY_delta, int nZ_delta);
> set the x,y,z-axes "nX_new","nY_new" from their current positions

void set_x_axis(int nX_new);
> set the x-axis to "nX_new"

void set_x_axis_rel(int nX_delta);
> set the x-axis "nX_delta" from its current position

void set_y_axis(int nY_new);
> set the y-axis to "nY_new"

void set_y_axis_rel(int nY_delta);
> set the y-axis "nY_delta" from its current position

void set_z_axis(int nZ_new);
> set the z-axis to "nZ_new"

void set_z_axis_rel(int nZ_delta);
> set the z-axis "nZ_delta" from its current position

--------
MOVEMENT
--------
void move(int nX_new, int nY_new, int nZ_new, bool orbit = false);
> move the object to "nX_new","nY_new","nZ_new"
> "orbit" is true  - the axes will remain fixed
             false - the axes will move with the object

void move_rel(int nX_delta, int nY_delta, int nZ_delta, bool orbit = false);
> move the object "nX_delta","nY_delta","nZ_delta" from its current position
> "orbit" is true  - the axes will remain fixed
             false - the axes will move with the object

void move_x(int nX_new);
> move the object to "nX_new"
> "orbit" is true  - the axes will remain fixed
             false - the axes will move with the object

void move_x_rel(int nX_delta, bool orbit = false);
> move the object "nX_delta" from its current position
> "orbit" is true  - the axes will remain fixed
             false - the axes will move with the object

void move_y(int nY_new);
> move the object to "nY_new"
> "orbit" is true  - the axes will remain fixed
             false - the axes will move with the object

void move_y_rel(int nY_delta, bool orbit = false);
> move the object "nY_delta" from its current position
> "orbit" is true  - the axes will remain fixed
             false - the axes will move with the object

void move_z(int nZ_new);
> move the object to "nZ_new"
> "orbit" is true  - the axes will remain fixed
             false - the axes will move with the object

void move_z_rel(int nZ_delta, bool orbit = false);
> move the object "nZ_delta" from its current position
> "orbit" is true  - the axes will remain fixed
             false - the axes will move with the object

--------
ROTATION
--------
void rotate(int x_angle_new, int y_angle_new, int z_angle_new);
> rotate the object to "x_angle_new","y_angle_new","z_angle_new" degrees

void rotate_rel(int x_angle_delta, int y_angle_delta, int z_angle_delta);
> rotate the object "x_angle_delta","y_angle_delta","z_angle_delta" degrees
  from its current x,y,z-degree rotation

void rotate_x(int x_angle_new);
> rotate the object to "x_angle_new" degrees about the x-axis

void rotate_x_rel(int theta);
> rotate the object "theta" degrees from its current x-degree rotation

void rotate_y(int y_angle_new);
> rotate the object to "y_angle_new" degrees about the y-axis

void rotate_y_rel(int theta);
> rotate the object "theta" degrees from its current y-degree rotation

void rotate_z(int z_angle_new);
> rotate the object to "z_angle_new" degrees about the z-axis

void rotate_z_rel(int theta);
> rotate the object "theta" degrees from its current z-degree rotation

-------
SCALING
-------
void scale(float x_scale_new, float y_scale_new, float z_scale_new);
> scale the object to "x_scale_new","y_scale_new","z_scale_new" percent

void scale_rel(float x_scale_delta, float y_scale_delta, float z_scale_delta);
> scale the object "x_scale_delta","y_scale_delta","z_scale_delta" percent
  from its current x,y,z-scale percentages

void scale_all(float xyz_scale_new);
> scale the object to "xyz_scale_new" percent for all three dimensions

void scale_all_rel(float xyz_scale_delta);
> scale the object "xyz_scale_delta" percent from its current x,y,z-scale
  percentages for all three dimensions

void scale_x(float x_scale_new);
> scale the object to "x_scale_new" percent

void scale_x_rel(float x_scale_delta);
> scale the object "x_scale_delta" percent from its current x-scale percentage

void scale_y(float y_scale_new);
> scale the object to "y_scale_new" percent

void scale_y_rel(float y_scale_delta);
> scale the object "y_scale_delta" percent from its current y-scale percentage

void scale_z(float z_scale_new);
> scale the object to "z_scale_new" percent

void scale_z_rel(float z_scale_delta);
> scale the object "z_scale_delta" percent from its current z-scale percentage

----------
STRETCHING
----------
void stretch(float x_stretch_new, float y_stretch_new, float z_stretch_new);
> stretch the object to "x_stretch_new","y_stretch_new","z_stretch_new"
  percent

void stretch_rel(float x_stretch_delta, float y_stretch_delta, float z_stretch_delta);
> stretch the object "x_stretch_delta","y_stretch_delta","z_stretch_delta"
  percent from its current x,y,z-stretch percentages

void stretch_x(float x_stretch_new);
> stretch the object "x_stretch_new" percent

void stretch_x_rel(float x_stretch_delta);
> stretch the object "x_stretch_delta" percent from its current x-stretch
  percentage

void stretch_y(float y_stretch_new);
> stretch the object "y_stretch_new" percent

void stretch_y_rel(float y_stretch_delta);
> stretch the object "y_stretch_delta" percent from its current y-stretch
  percentage

void stretch_z(float z_stretch_new);
> stretch the object "z_stretch_new" percent

void stretch_z_rel(float z_stretch_delta);
> stretch the object "z_stretch_delta" percent from its current z-stretch
  percentage

EXAMPLE PROGRAM:

#include "bestcpp.hpp"

/* vector coordinates */
// x,y,z of every vertex
// 32767  end of object
int pic_box[] = {
   -60,  -40,   80, // box body             //    0  left  up   towards
   -60,   40,   80,                         //    3  left  down towards
    60,   40,   80,                         //    6  right down towards
    60,  -40,   80,                         //    9  right up   towards

   -60,  -40,  -80,                         //   12  left  up   away
   -60,   40,  -80,                         //   15  left  down away
    60,   40,  -80,                         //   18  right down away
    60,  -40,  -80,                         //   21  right up   away

    32767
};

/* data describing each vector */
// -2  new polygon (enclosed), number of vertexes, vertex offset
// -1  new polygon (not enclosed), number of vertexes, vertex offset
//  32767  end of object
int pic_box_data[] = {
    -2,   4,   9, lightgreen,               // front surface of box
               6, lightgreen,
               3, lightgreen,
               0, lightgreen,
    -2,   4,  12, lightgreen,               // back surface of box
              15, lightgreen,
              18, lightgreen,
              21, lightgreen,
    -2,   4,   0, lightgreen,               // left surface of box
               3, lightgreen,
              15, lightgreen,
              12, lightgreen,
    -2,   4,  21, lightgreen,               // right surface of box
              18, lightgreen,
               6, lightgreen,
               9, lightgreen,
    -2,   4,  21, lightgreen,               // top surface of box
               9, lightgreen,
               0, lightgreen,
              12, lightgreen,
    -2,   4,   6, lightgreen,               // bottom surface of box
              18, lightgreen,
              15, lightgreen,
               3, lightgreen,

    32767
};

void main()
{
  video.set(_640x480x256);

  _3d_object_vector box(nX_max/2, nY_max/2, 0, pic_box, pic_box_data);
  box.move_rel(10, -10, 10);           // move box
  box.rotate_rel(10, 10, 0);           // rotate box
  box.scale_rel(0.80, 0.70, 0.50);     // scale box
  box.stretch_rel(0.80, 0.70, 0.50);   // stretch box
  box.set_wireframe(true);             // show box in wireframe
}

==============================================================================
Primitives
==========

COMMON TO ALL GRAPHIC PRIMITIVES
--------------------------------
int get_color();
> RETURNS  object's color

void set_color(int nColor_new);
> set the object's color to "nColor_new"

COMMON TO ALL GRAPHIC PRIMITIVES THAT ARE ENCLOSED SHAPES
---------------------------------------------------------
void interact_stretch();
> if a stretch key was pressed, the object is stretched appropriately

bool is_solid();
> RETURNS  true  - the object is solid
           false - the object is an outline

void set_keys_stretch(byte *ayKeysStretch_new);
> "ayKeysStretch_new" become the stretch keys

void set_solid(bool bSolid_new);
> "bSolid_new" is true  - object is solid
                  false - object is an outline

COMMON TO ALL GRAPHIC PRIMITIVES WITH ONE LENGTH
------------------------------------------------------
int get_length();
> RETURNS  length of object

void stretch(int nLength_new);
> set the object's length to "nLength_new"

void stretch_rel(int nLength_delta);
> set the object's length "nLength_delta" from its current length

COMMON TO ALL GRAPHIC PRIMITIVES WITH ONE LENGTH AND ONE HEIGHT
-----------------------------------------------------------------
int get_height();
> RETURNS  height of object

int get_length();
> RETURNS  length of object

void set_height(int height_new);
> set the object's height to "height_new"

void set_length(int length_new);
> set the object's length to "length_new"

void set_height_rel(int height_delta);
> set the object's height "height_delta" from its current height

void set_length_rel(int length_delta);
> set the object's length "length_delta" from its current length

void stretch(int nLength_new, int nHeight_new);
> set the object's dimensions to "nLength_new","nHeight_new"

void stretch_rel(int nLength_delta, int nHeight_delta);
> set the object's dimensions "nLength_delta","nHeight_delta" from its current
  dimensions

COMMON TO ALL GRAPHIC PRIMITIVES WITH TWO LENGTHS AND TWO HEIGHTS
---------------------------------------------------------------------
int get_height1();
> RETURNS  height #1 of object

int get_height2();
> RETURNS  height #2 of object

int get_length1();
> RETURNS  length #1 of object

int get_length2();
> RETURNS  length #2 of object

void set_height1(int nHeight1_new);
> set the object's height #1 to "nHeight1_new"

void set_height2(int nHeight2_new);
> set the object's height #2 to "nHeight2_new"

void set_length1(int nLength1_new);
> set the object's length #1 to "nLength1_new"

void set_length2(int nLength2_new);
> set the object's length #2 to "nLength2_new"

void set_height1_rel(int nHeight1_delta);
> set the object's height #1 "nHeight1_delta" from its current height #1

void set_height2_rel(int nHeight2_delta);
> set the object's height #2 "nHeight2_delta" from its current height #2

void set_length1_rel(int nLength1_delta);
> set the object's length #1 "nLength1_delta" from its current length #1

void set_length2_rel(int nLength2_delta);
> set the object's length #2 "nLength2_delta" from its current length #2

void stretch(int nLength1_new, int nHeight1_new, int nLength2_new, int nHeight2_new);
> set the object's dimensions to "nLength1_new","nHeight1_new",
  "nLength2_new","nHeight2_new"

void stretch_rel(int nLength1_delta, int nHeight1_delta, int nLength2_delta, int nHeight2_delta);
> set the object's dimensions "nLength1_delta","nHeight1_delta",
  "nLength2_delta","nHeight2_delta" from its current dimensions

COMMON TO ALL GRAPHIC PRIMITIVES WITH ONE RADIUS
--------------------------------------------------------
int get_radius();
> RETURNS  object's radius

void stretch(int nRadius_new);
> set the object's radius to "nRadius_new"

void stretch_rel(int nRadius_delta);
> set the object's radius "nRadius_delta" from its current radius

COMMON TO ALL GRAPHIC PRIMITIVES WITH TWO RADII
-------------------------------------------------------
int get_radius_x();
> RETURNS  object's major radius (along x-axis)

int get_radius_y();
> RETURNS  object's minor radius (along y-axis)

void set_radius_x(int nRadiusx_new);
> set the object's major radius to "nRadiusx_new"

void set_radius_x_rel(int nRadiusx_delta);
> set the object's major radius "nRadiusx_delta" from its current major
  radius

void set_radius_y(int nRadiusy_new);
> set the object's minor radius to "nRadiusy_new"

void set_radius_y_rel(int nRadiusy_delta);
> set the object's minor radius "nRadiusy_delta" from its current minor
  radius

void stretch(int nRadiusx_new, int nRadiusy_new);
> set the object's radii to "nRadiusx_new","nRadiusy_new"

void stretch_rel(int nRadiusx_delta, int nRadiusy_delta);
> set the object's radii "nRadiusx_delta","nRadiusy_delta" from their
  current radii

COMMON TO ALL GRAPHIC PRIMITIVES WITH ONE RADIUS AND TWO ANGLES
-----------------------------------------------------------------------
int  get_angle_end();
> RETURNS  object's ending angle

int  get_angle_start();
> RETURNS  object's beginning angle

void set_angle_end(int nAngleEnd_new);
> set the object's ending angle to "nAngleEnd_new"

void set_angle_start(int nAngleStart_new);
> set the object's starting angle to "nAngleStart_new"

void set_angle_end_rel(int nAngleEnd_delta);
> set the object's ending angle "nAngleEnd_delta" from its current measure

void set_angle_start_rel(int nAngleStart_delta);
> set the object's starting angle "nAngleStart_delta" from its current measure

void stretch(int nAngleStart_new, int nAngleEnd_new);
> set the object's angles to "nAngleStart_new","nAngleEnd_new"

void stretch_rel(int nAngleStart_delta, int nAngleEnd_delta);
> set the object's angles "nAngleStart_delta","nAngleEnd_delta" from its
  current measures

------------------------------------------------------------------------------
arc (not yet written)
---
NOTES:
> graphic primitive that is an enclosed shape with one radius and two angles

constructor:
  _2d_arc(int nX_init, int nY_init, int nRadius_init,
          int nAngleStart_init, int nAngleEnd_init,
          int nColor_init, bool bSolid_init, bool bVisible_init = true);
> "nX_init","nY_init" are the arc's coordinates
> "nRadius_init" is the radius
> "nAngleStart_init","nAngleEnd_init" are the beginning/ending angles
> "nColor_init" is the color
> "nSolid_init" is true  - arc is solid
                   false - arc is an outline
> "bVisible_init" is true  - arc is visible
                     false - arc is not visible

EXAMPLE PROGRAM:

#include "bestcpp.hpp"

void main()
{
  video.set(_640x480x256);

  _2d_arc myarc(nX_max/2, nY_max/2, 64, 30, 210, yellow);
  myarc.move(10, -5);                  // move arc right and up
  myarc.stretch_rel(10, -5);           // change arc's angles
}

------------------------------------------------------------------------------
circle
------
NOTES:
> graphic primitive that is an enclosed shape with one radius

constructor:
  _2d_circle(int nX_init, int nY_init, int nRadius_init,
             int nColor_init, bool bSolid_init, bool bVisible_init = true);

> "nX_init","nY_init" are the circle's coordinates
> "nRadius_init" is the radius
> "nColor_init" is the color
> "bSolid_init" is true  - circle is solid
                   false - circle is an outline
> "bVisible_init" is true  - circle is visible
                     false - circle is not visible

EXAMPLE PROGRAM:

#include "bestcpp.hpp"

void main()
{
  video.set(_640x480x256);

  _2d_circle mycircle(nX_max/2, nY_max/2, 64, yellow);
  mycircle.move(10, -5);               // move circle right and up
  mycircle.stretch_rel(-16);           // change circle radius
}

------------------------------------------------------------------------------
ellipse
-------
NOTES:
> graphic primitive that is an enclosed shape with two radii

constructor:
  _2d_ellipse(int nX_init, int nY_init, int nRadiusX_init, int nRadiusY_init,
              int nColor_init, bool bSolid_init, bool bVisible_init = true);
> "nX_init","nY_init" are the ellipse's coordinates
> "nRadiusX_init","nRadiusY_init" are the radii
> "nColor_init" is the color
> "bSolid_init" is true  - ellipse is solid
                   false - ellipse is an outline
> "bVisible_init" is true  - ellipse is visible
                     false - ellipse is not visible

EXAMPLE PROGRAM:

#include "bestcpp.hpp"

void main()
{
  video.set(_640x480x256);

  _2d_ellipse myellipse(nX_max/2, nY_max/2, 64, 32, yellow);
  myellipse.move(10, -5);              // move ellipse right and up
  myellipse.stretch_rel(-16, 8);       // change ellipse radii
}

------------------------------------------------------------------------------
line
----
NOTES:
> graphic primitive with one length and height

constructor:
  _2d_line(int nX_init, int nY_init, int nLength_init, int nHeight_init,
           int nColor_init, bool bVisible_init = true);
> "nX_init","nY_init" are the line's coordinates
> "nLength_init","nHeight_init" are the dimensions
> "nColor_init" is the color
> "bVisible_init" is true  - line is visible
                     false - line is not visible

EXAMPLE PROGRAM:

#include "bestcpp.hpp"

void main()
{
  video.set(_640x480x256);

  _2d_line myline(nX_max/2, nY_max/2, 64, -32, yellow);
  myline.move(10, -5);                 // move line right and up
  myline.stretch_rel(-16, -8);         // change line dimensions
}

------------------------------------------------------------------------------
pixel
-----
NOTES:
> graphic primitive

constructor:
  _2d_pixel(int nX_init, int nY_init,
            int nColor_init, bool bVisible_init = true);
> "nX_init","nY_init" are the pixel's coordinates
> "nColor_init" is the color
> "bVisible_init" is true  - pixel is visible
                     false - pixel is not visible

EXAMPLE PROGRAM:

#include "bestcpp.hpp"

void main()
{
  video.set(_640x480x256);

  _2d_pixel mypixel(nX_max/2, nY_max/2, yellow);
  mypixel.move(10, -5);                 // move pixel right and up
  mypixel.set_color(lightblue);         // change pixel color
}

------------------------------------------------------------------------------
rectangle
---------
NOTES:
> graphic primitive that is an enclosed shape with a length and height

constructor:
  _2d_rectangle(int nX_init, int nY_init, int nLength_init, int nHeight_init,
                int nColor_init, bool bSolid_init, bool bVisible_init = true);
> "nX_init","nY_init" are the rectangle's coordinates
> "nLength_init","nHeight_init" are the dimensions
> "nColor_init" is the color
> "bSolid_init" is true  - rectangle is solid
                   false - rectangle is an outline
> "bVisible_init" is true  - rectangle is visible
                     false - rectangle is not visible

EXAMPLE PROGRAM:

#include "bestcpp.hpp"

void main()
{
  video.set(_640x480x256);

  _2d_rectangle myrectangle(nX_max/2, nY_max/2, 64, -32, yellow);
  myrectangle.move(10, -5);            // move rectangle right and up
  myrectangle.stretch_rel(-16, -8);    // change rectangle dimensions
}

------------------------------------------------------------------------------
square
------
NOTES:
> graphic primitive that is an enclosed shape with one length

constructor:
  _2d_square(int nX_init, int nY_init, int nLength_init,
             int nColor_init, bool bSolid_init, bool bVisible_init = true);
> "nX_init","nY_init" are the square's coordinates
> "nLength_init" is the length of each side
> "nColor_init" is the color
> "bSolid_init" is true  - square is solid
                   false - square is an outline
> "bVisible_init" is true  - square is visible
                     false - square is not visible

EXAMPLE PROGRAM:

#include "bestcpp.hpp"

void main()
{
  video.set(_640x480x256);

  _2d_square mysquare(nX_max/2, nY_max/2, 64, -32, yellow);
  mysquare.move(10, -5);               // move square right and up
  mysquare.set_length_rel(-16);        // change square size
}

------------------------------------------------------------------------------
triangle (not yet written)
--------
NOTES:
> graphic primitive that is an enclosed shape with two lengths and two heights

constructor:
  _2d_triangle(int nX_init, int nY_init, int nLength1_init, int nHeight1_init,
               int nLength2_init, int nHeight2_init,
               int nColor_init, bool bSolid_init, bool bVisible_init = true);
> "nX_init","nY_init" are the triangle's coordinates
> "nLength1_init","nHeight1_init" are the dimensions of the first side
> "nLength2_init","nHeight2_init" are the dimensions of the second side
> "nColor_init" is the color
> "bSolid_init" is true  - triangle is solid
                   false - triangle is an outline
> "bVisible_init" is true  - rectangle is visible
                     false - rectangle is not visible

EXAMPLE PROGRAM:

#include "bestcpp.hpp"

void main()
{
  video.set(_640x480x256);

  _2d_triangle mytriangle(nX_max/2, nY_max/2, 64, -32, -16, 128, yellow);
  mytriangle.move(10, -5);               // move triangle right and up
  mytriangle.set_dimensions_rel(-8, 16, 4, -64);
}

==============================================================================
Screen Fills
============
NOTES:
> video.clear(54) and video.clear(55) produce strange
  results.  If the library was not compiled with Automatic Register
  Variables, it would work fine.  This is an error in the Borland C++ 3.1
  compiler, and not my fault.

------------------------------------------------------------------------------
background patterns
-------------------
void video.bg(int whichOne, int color);
> fill the current viewport with pattern "whichOne" in "color"
> "whichOne" is 0 - circles expanding outward
                1 - radial lines of increasing color
                2 - unusually placed lines
                3 - unusually placed lines

------------------------------------------------------------------------------
screen clears
-------------
void video.clear(int how, int ms_delay = 1, int color = black);
> clear the current viewport with pattern "how" to "color"
> pause "ms_delay" milliseconds between each output
> "how" is 0  - straight lines top to bottom
           1  - straight lines bottom to top
           2  - straight lines left to right
           3  - straight lines right to left
           4  - straight lines top and bottom open
           5  - straight lines top and bottom close
           6  - straight lines left and right open
           7  - straight lines left and right close
           8  - diagonal lines at 45° bottom-left to top-right
           9  - diagonal lines at 45° bottom-right to top-left
           10 - diagonal lines at 45° top-right to bottom-left
           11 - diagonal lines at 45° top-left to bottom-right
           12 - diagonal lines at 45° bottom-left and top-right open
           13 - diagonal lines at 45° bottom-left and top-right close
           14 - diagonal lines at 45° bottom-right and top-left open
           15 - diagonal lines at 45° bottom-right and top-left close
           16 - radial lines counterclockwise
           17 - radial lines clockwise
           18 - radial lines clock-like top clockwise
           19 - radial lines clock-like top counterclockwise
           20 - radial lines clock-like left clockwise
           21 - radial lines clock-like left counterclockwise
           22 - radial lines clock-like bottom clockwise
           23 - radial lines clock-like bottom counterclockwise
           24 - radial lines clock-like right clockwise
           25 - radial lines clock-like right counterclockwise
           26 - radial lines clock-like meet at bottom
           27 - radial lines clock-like meet at right
           28 - radial lines clock-like meet at top
           29 - radial lines clock-like meet at left
           30 - radial lines wiper-like bottom center open
           31 - radial lines wiper-like bottom center close
           32 - radial lines wiper-like right center open
           33 - radial lines wiper-like right center close
           34 - radial lines wiper-like top center open
           35 - radial lines wiper-like top center close
           36 - radial lines wiper-like left center open
           37 - radial lines wiper-like left center close
           38 - radial lines wiper-like bottom-left clockwise
           39 - radial lines wiper-like bottom-left counterclockwise
           40 - radial lines wiper-like bottom-right clockwise
           41 - radial lines wiper-like bottom-right counterclockwise
           42 - radial lines wiper-like top-right clockwise
           43 - radial lines wiper-like top-right counterclockwise
           44 - radial lines wiper-like top-left clockwise
           45 - radial lines wiper-like top-left counterclockwise
           46 - radial lines wiper-like bottom-left open
           47 - radial lines wiper-like bottom-left close
           48 - radial lines wiper-like bottom-right open
           49 - radial lines wiper-like bottom-right close
           50 - radial lines wiper-like top-right open
           51 - radial lines wiper-like top-right close
           52 - radial lines wiper-like top-left open
           53 - radial lines wiper-like top-left close
           54 - rectangles expanding outward
           55 - rectangles collapsing inward

==============================================================================
Windowing
=========

Not yet documented.

==============================================================================


==============================================================================
---------------------------------  KEYBOARD  ---------------------------------

NOTES:
> "key" is a globally accessible class of "keyboard_def".

not yet documented

==============================================================================
----------------------------------  STRING  ----------------------------------

==============================================================================
String (not yet written)
======
NOTES:
> All strings are NULL-terminated.

void clean(char& str);
> remove all control characters from "str"

int hash(const char& str);
> RETURNS  hashed value of "str" (sum of all characters' ASCII values)

char *left(const char& str, int num);
> RETURNS  string containing "num" characters of "str", counting from left

char *mid(const char& str, int start, int num);
> RETURNS  string containing "num" characters of "str", counting from "start"

void replace(char& str, const char& replace, int num, int start)
> inside "str", replace "num" characters beginning at "start" with "replace"

char *right(const char& str, int num);
> RETURNS  string containing "num" characters of "str", counting from right

char *sentence(const char& str);
> RETURNS  sentence form of "str": first letter capitalized, period appended

void substitute(char& str, const char& search, const char& replace,
                int num = 0, int nth = 1)
> inside "str", replace occurrences of "serach" with "replace"
> perform "num" substitutions (if = 0, substitute every occurrence)
> begin substitution at the "nth" occurrence (1 means first occurrence)

==============================================================================

==============================================================================
---------------------------------  TEXT MODE  --------------------------------

NOTES:
> "txt" is a globally accessible class of "txt_screen_def".
> "video" is a globally accessible class of "video_def".
> since the DOS screen is the first text window, do not modify this window if
  you wish to restore the DOS screen properly when your program exits
  > to use the DOS screen and still restore it, just create another window
    and save it (it will copy the screen contents into the new window)

not yet documented

==============================================================================
Cursor
======

not yet documented

==============================================================================
Special Effects
===============

not yet documented

==============================================================================
Windowing
=========

not yet documented

==============================================================================
-----------------------------------  TIMER  ----------------------------------

NOTES:
> Timer identification numbers start at 0 and increase by 1 (so the first timer
  has timer_id = 0, the second has timer_id = 1, ...).
> If you supply a timer_id that is greater than the number of timers, then the
  next free timer_id will be used and returned.  For example:
    timer timers(2);                   // allocate timers (timer_id 0, 1)
    word id = timers.set(10, 5);       // id = 2 and a new timer is allocated
                    // now there are three allocated timers (wTimerId 0, 1, 2)

constructor: timer(word wNumber_init = 1);
> initially set up "wNumber_init" timers

bool done(word wTimerId);
> RETURNS  true  - "wTimerId" has finished
           false - "wTimerId" has not yet finished

word get_number();
> RETURNS  current number of timers

word set(word nLength);
> create a new timer and set it to "nLength" clock ticks
> RETURNS  id of timer created

void set(TimerId, word nLength);
> set "wTimerId" to "nLength"

void reset(word wTimerId);
> reset "wTimerId" to 0

EXAMPLE PROGRAM:

#include "bestcpp.hpp"

void main()
{
  timer stopwatch;                     // one timer initially
  timer tm(2);                         // two timers initially
  tm.set(0, 10);                       // set first timer to 10 clock ticks
  tm.set(1, 15);                       // set second timer to 15 clock ticks

  tm.set(5, 18);                       // more timers will be created
  /* since there were only 2 timers and we specified wTimerId = 5, timers
     upto wTimerId = 5 will be created automatically */

  word j = tm.set(21);           // this will create a new timer, set it to
  cout << "j = " << j << endl;   //  21 clock ticks and return its id (to j)
}

==============================================================================

======================== END OF LIBRARY DOCUMENTATION ==========================


==============================================================================
-------------------------  HOW TO CONTACT THE AUTHOR  ------------------------

If you have any comments or questions regarding this library or any other
program written by me, George Vanous, feel free to reach me via email at
  [e-mail]
or call me at [phone] or write to me:  George Vanous
                                             8930 Watson Court
                                             Delta, BC, CAN
                                             V4C 4T6

==============================================================================
---------------------------  PROGRAMMING PITFALLS  ---------------------------

= in a multi-file project where the files not being edited are linked in as
  .OBJs, take GREAT care to update the .OBJs when the .HPP files they use are
  updated
  - if this is not done, the wrong functions may be called (hide may call show)
= new char[100];                       // this makes an array of char
  new (char *)[100];                   // this DOES NOT make an array of char *
  - (char *) is interpreted as a type cast and makes an array of integers
  - to make an array of char pointers, you must create a new type:
    typedef char * pChar;
    new pChar[100];                    // this makes an array of char *
= never hold onto addresses of variables declared inside a function
  - when the function terminates, these variables are destroyed
  - if you try to write to these now-nonexistent variable address: BOOM!
= enums are considered to be 2-byte ints
  - enum bool { false, true} does not take 1 byte, but 2 bytes to store
= bool is_empty() { return bool(head); }
  - is head = 0, is_empty should return true
  - this needs to be written return bool(!head);
= take great care to dynamically allocate enough memory and initialize pointers
= beware of endless loops:
    int i = 0;
    while (i < 5)
      anWindowID[i]->show();  // FORGOT THE INCREMENT -> ...[i++]->show();
= compiler complaints:
  - unreachable code
    - neverending loop (ie. while (1 < 10) instead of while (i < 10))
    - premature return statement
= computer simulations of Michael Jordan:
  - jams during compilation: unbalanced braces
  - jams before execution: a breakpoint inside an include file
= repeat rate on keyboard is unusually slow
  - you may be calling a clear_buffer() function just prior to calling get_ch()
= always put only one command inside a ternary operator if/else slot:
    y = ((x == 2) ? 1 : 0);
  - NEVER do something like this (only ONE command (not both) is executed):
    ((x == 2) ? move(1, 0); y = 0 : move(0, 1); y = 1);
= if (x == 2)
    if (y == 2)
      z = 0;
  else                  // WARNING  this "else" is with the second "if"
    z = 1;
  - if y != 2, then z = 1 -- IOW, here is how the compiler interprets this:
      if (x == 2)
        if (y == 2)
          z = 0;
        else
          z = 1;
  - to associate the "else" with the first "if", use braces:
      if (x == 2) {
        if (y == 2)
          z = 0;
      }
      else
        z = 1;

==============================================================================
-----------------------------  PROGRAMMING TIPS  -----------------------------

= to save compile time in a multi-file project, change the project to include
  the .OBJs of those files that are not being edited
= if testing for zero or nonzero, user ! and (blank) -- faster
  - bad:  if (empty == 0)   or   if (keypressed == 1)
  - good: if (!empty)       or   if (keypressed)
= for infinite loops, use while (true) instead of for (;;) -- faster
= minimize number of memory allocations -- faster
  - bad:  icon = new int[100]; icon_bg = new int[100];
  - good: icon = new int[200]; icon_bg = icon+100;
= use "#define"s instead of "const"s because "#define"s don't use up memory
= use inline keyword for short functions -- faster
= use static keyword for often-used functions -- less memory
  - static functions are not passed a this pointer, it must be done explicitly
= to remove warning of "parameter not used" in, for example, main:
    main(int, char **, char **)
  unnamed parameters do not receive these warnings
= try to declare all loop variables just before the loop, and as single
  letters of type int:
    int i;
    for (i = 0; i < nLength; i++) { ... }
= use unnamed local variables if they are used only once:
    main(int, char **) {
      return DApp().Run();
    }
  instead of:
    main(int, char **) {
      DApp MinApp;
      return MinApp.Run();
    }
  or, worse yet:
    main(int, char **) {
      DApp *pMinApp;
      int iRetVal;

      pMinApp = new DApp();
      iRetVal = pMinApp->Run();
      delete pMinApp;

      return iRetVal;
    }
= all typedef struct should have a tag:
    typedef struct tagRECT {
      int left;
      int top;
      int right;
      int bottom;
    } RECT;
  this will allow referencing this structure inside it (like for linked lists)

==============================================================================
-----------------------------  PROGRAMMING IDEAS  ----------------------------

= TEXT MODE
  - text file cataloging/indexing with a personal diary section (like GPE)
  - CD-ROM cataloging software (like the one on the Tech Arsenal CD)
    - create a FILES.BBS format
      - allow one line description to encourage brevity and conciseness
    - user can create a USEFUL section where he documents his useful programs
      - used as a quick-reference, instead of browsing entire CD-ROM
  - quick calendar pop-up
= file randomizer that will pick from a list of files to copy to one file
  - great for randomizing the startup screen for BBS's
= sphere rotation with name rotating on surface of sphere
= installation program exactly like Symantec's Norton Utilities 8.0
= C++ tutorial (actually, any language tutorial)
= C to Pascal converter (and Pascal to C)
= a program that will train memory by reviewing knowledge (integrate with REdit)
  - maybe even a TSR that pops up occassionally
  - also one that pops up random letters/words/numbers and asks them to be
    repeated (backwards or forwards) and keeps records of progress
    - also has world averages for this sort of thing for comparison (IQ style)
= cable tray program
= 3-dimensional spreadsheet
= document cover all facets of psychology behind commercials and human control
  - similar to Stutfen's the Battle for Your Mind -- not as superficial
  - cover all aspects of society, such as Mofia and other underestimated groups
    - standard psychological tricks used by commercials
      - repetitiveness
      - brainwashing attempts
        - subliminal messages
          - hidden behind music
          - flashing too fast for conscious cognition
      - humor
        - "I don't know why I throw these small parties.  A few people I don't
           know, a few people I don't like.  The only thing I am not being
           hassled about is my fine choice of beer.  I don't know why I throw
           these small parties.  I should throw a big one."
      - celebrities state their preference to that project
= REGISTRATION IDEAS
  - input subliminal messages to encourage registration: "register"
  - at end of program, have little guy walk up with sign saying "Register"
= SPECIAL EFFECTS
  - clear the screen with two yellow lines moving up from the center, clearing
    as they go (like in The Gathering '94, TG94INV!, introduction)
    - stop to create a small message window, display quick message
    - then, clear screen by going all the way up
  - scroller that looks like going over rapids (stretched) at some points
  - for a title of a program, superimpose one word (in brighter colors) onto
    another word (larger, of course) (remember Just Buttons)
  - a ball on chain swinging into and out of the screen (for 3D effect)
  - starfield layers (like BB-TP4.ZIP)
    - move pixels across the screen, the further ones darker colored
  - clear the screen by starting at a corner and drawing a straight line,
    sweeping it around the screen
    - do this at each corner for a neat effect (like DEMOAI.EXE, HDILOAD demo)
  - 3D rotating Rubik's Cube
  - 3D rotating opitcal illusion (three prongs).
  - water/wave effect (top view)
    - have the water "on top" of a bitmap, and distort it
  - Spotlight effect (with shadows)
  - Film countdown (leader) for beginning of demo
  - End scroller where it starts scrolling when there is something going on in
    the background, then the background fades to black and the scroller
    continues (like in the movies)
  - 64 pixels of a picture placed randomly on screen
    - come together in 64 steps each to form the picture
  - similar to ULTRAMOD.EXE, have a window (of very dark grey background) and
    a totally black background outside this window
    - move this window around, showing different sections of the screen
= GAMES
  - obstacle course
    - REMEMBER: house rotation with one house in the center orbited by two
                houses (orbiting in opposite directions) -- you could just make
                it out of the center by moving to the right, but not to the left
                because, to the right, the rooves, being slanted, offered a
                little more time before collision
  - dig dug
  - pong kombat
    - like original pong with fatalities
  - Mario brothers like game for 2-player simple fun
  - Super-Mario brothers like game where one jumps around a lot
  - space invaders (like on Intelivision)
  - asteroids
  - arkanoid
  - tank wars
    - two tanks on screen moving around
    - limited shot range and bounce of wall option (default on)
    - buy weapons (grenades, mines, shoot-over-wall shots, etc.)
  - pac-man (CD-MAN)
    - large, scrolling screen (also a version with full screen viewed)
    - random maze option
    - multiplayer option (modem/network/simultaneous)
  - space invaders
    - control a ship on the bottom (possibly with some protective blocks)
    - shoot the aliens that are slowly moving down toward you
    - the occassional flying saucer flies across the top of the screen (bonus)
  - from netnews article, women say they like Tetris because it is non-violent
    and is self-competitive (there is no monster or villian to defeat)
    - "multiple paths to winning and is in competition with yourself, not
      another "monster" or player"
    - try incorporating this idea into a game
  - Ultima V/Sword Quest style game
  - Slip N' Slide type car racing game
    - similar to OffRoad
  - look at Texas Instruments games
    - Car Wars
    - Munch Man
    - Parsec
  - look at Commodore games
    - Mario Brothers
    - Space Taxi
    - Oil's Well
  - Castle of the Winds/Sword Quest/Legend of Zelda game
  - have credits inside the game (like Corridor 7)
    - as you walk around, show them on walls, maybe floating in the air
    - just in the beginning of the game
  - big-top game
  - catchem game
  - tank game of two players onscreen with rebounding bullets (like Atari tanks)
    - planes flying around the screen trying to shoot each other
  - Zoarre-type VGA 16 color DND game (old DND like Teleguard)
  - a game like realtime risk (no waiting for turn) (with time-limit option)
    - winner is who can click the fastest
    - no army fighting -- just click on square to capture it
  -
                                Dinosaur!
                 an action packed arcade/adventure game
                 with stunning high-intensity graphics
                      by well known graphic artist
                            Thaddeus Jantzi!

        Here is a brief run down of my ideas of the ideal format for it..
        Any modifactions that might help, or need be made can easily be
        accomodated

Opening screen: Giant letters saying "DINOSAUR!" with a little caveman shown
                running

Next screen: Welcome screen.  Here the player enters his name, selects
             Carnivore or Herbivore, and then selects his Dinosaur of
             the following possible

             CARNIVORES               HERBIVORES
             Tyrannosaur              Triceratops
             Allosaur                 Stegosaur
             Dimetrodon               Pteranodon

             Other dinosaurs will be added (by me) later
             This is iffy... but it would be neat if the player could design
             his own dinosaur.  That can be arranged later if possible

Game!
The player will work his way through a number of levels.

Players must avoid obstacles such as volcanoes, falling rocks, lightning bolts
earthquakes, rivers and lakes.

The object for a carnivore is to destroy as much foliage as possible, and
destroy a herbivore at the end of each level.

The object for a herbivore is to eat as much foliage as possible and protect
itself from a carnivore at the end of each level.

Each dinosaur will have two attacks... defined on the selection screen

High scores will be based on foliage eaten, destroyed, etc.

==============================================================================
---------------------------  PROGRAMMING QUESTIONS  --------------------------

Q what is this LIFE program I see in many BASIC compilers?
Q what is a good algorithm to generate a maze that always has a solution?
Q how to scroll smoothly horizontally/vertically in text and graphics mode
Q how to safely reprogram the timer chip to oscillate x times faster
Q how doe one find out where the "null pointer assignment" is occurring?
  A set a watch on the following expressions:
      *(char *)0,4m
      *(char *)4
    and step through the program; when the values change, the just-executed
    line is the one that is causing the problem

==============================================================================
---------------------------------  DOS DEBUG  --------------------------------

a        - begin assembly (mov ax,bx    shr cx,1    etc.)
e        - begin hex input at the current offset
u        - unassemble (show the assembler instructions)
d     - show a memory dump (hex values)
d100     - show a memory dump beginning at offset 100 hex
da000:10 - show a memory dump beginning at segment A000 offset 10 hex
NOTE     - this convention of appending numbers also works for a, e and u

r        - show the current register contents
rax      - register AX (set a value for register AX)
rbx...   - register BX, register CX (rcx) (rdx, rbp, rds, etc.)
t        - trace the next instruction (like F7 in Pascal)
p        - proceed through the next instruction (like F8 in Pascal)
NOTE     - the difference between t and p is very important!  If the next
           instruction is a CALL, then t will trace INTO that call whereas p
           will treat CALL as one instruction.  p will perform the call and
           return control to you after the call has completed.

==============================================================================
------------------------------  FREEWARE TITLES  -----------------------------

This list is woefully incomplete.  If you can add on to it, please contact me.

---

GAME PROGRAMMER'S ENCYCLOPEDIA
 - excellent source of tutorials and demos with full source
 - WHERE IS IT?  teeri.oulu.fi  pub/msdos/programming/gpe/pcgpe10.zip

---

LINUX
 - probably the best operating system for the 386+ PC (undeniably the fastest)
 - supports DOS, OS/2, WINDOWS NT, etc. disk file formats
 - WHERE IS IT?  (unknown ftp site)

---

THE BESTLIBRARY++
 - robust C++ object library (author welcomes code contributions)
 - WHERE IS IT?  still under development -- contact author at [e-mail]

---

==============================================================================
--------------------------------  DISCLAIMER  --------------------------------

To the best of my ability (and that is damn good), I have made all versions of
The BESTLibrary++ error free, compatible with all IBM PC clones, and free of
viruses, trojans, and the common cold.  I, or anybody related to the
development of this software, cannot be held accountable for the behavior of
the enclosed program(s) or file(s) and assume no liability for damages either
from the direct use or as a consequence of the use/misuse of this product.
Hence, this program and all information contained within should be used at
one's own risk.

This disclaimer is included to absolve me from the legal issues brought about
by today's litigious society.

==============================================================================

===PERSONAL NOTES

To rotate vector A about vector B (right hand rule), theta radians:
  new vector = Dot(A,B)*B + Sin(theta)*Cross(B,A) + Cos(theta)*Dot(B,Cross(A,B))

= make two versions for each data type:
  - 1) take in pointers to objects
  - 2) take in objects
= make a version that serves as a tutorial (for novices)
  - show them step-by-step how to use the common functions

FILE_ID.DIZ
Robust FREEWARE C++ object library with
full source code!  2D/3D graphics, data
types, text mode control, text/graphics
windows, timers and stopwatches, direct
keyboard control, and much more!

==============================================================================

REALiTY